W06-2. Kubernetes 입문 - 실습 가이드

6주차 실습: 내 노트북에 Kubernetes 클러스터 만들고 Pod 띄우기

실습 목표 (45분)

  • Docker Desktop 으로 노드 3개짜리 Kubernetes 클러스터를 만든다.
  • kubectl 로 클러스터와 시스템 구성 요소를 들여다본다.
  • 4주차에 Docker Hub 에 올린 방명록을 Pod 로 띄우고 브라우저로 접속한다.
  • 일부러 고장 낸 Pod(ImagePullBackOff, CrashLoopBackOff)를 진단한다.

시작 전 확인

  • Docker Desktop 실행 중, Docker Desktop 에 로그인되어 있음
  • Docker Hub 에 내아이디/guestbook:v1 이 올라가 있음 (4주차 실습 6)
    • 못 올렸다면 아래 대안을 보세요.
  • 노트북 메모리 여유: 클러스터가 약 2~3GB 를 씁니다. 안 쓰는 프로그램은 닫아 주세요.
  • 터미널: macOS → 터미널 / Windows → PowerShell. kubectl 명령은 두 OS 가 똑같습니다.

실습 내용 시간
0 클러스터 만들기 8분
1 클러스터 둘러보기 7분
2 첫 Pod (명령형) 5분
3 방명록 Pod (YAML, 선언형) 10분
4 Pod 를 지우면? 2분
5 고장 난 Pod 진단하기 8분
6 Namespace 3분
7 정리 2분

실습 0. 클러스터 만들기

0-1. Docker Desktop 에서 만들기

  1. Docker Desktop 대시보드 왼쪽 메뉴에서 Kubernetes 를 누릅니다.
  2. Create cluster 를 누릅니다.
  3. 클러스터 종류에서 kind 를 고릅니다.
    • Nodes(노드 수): 3 (메모리가 8GB 인 노트북이면 2)
    • Version: 기본값 그대로
  4. Create 를 누르고 1~2분 기다립니다. 처음에는 노드 이미지를 받느라 더 걸릴 수 있습니다.
  5. 대시보드 아래쪽(또는 Kubernetes 화면)에 Kubernetes running 이 보이면 완료입니다.
kubeadm 과 kind 중 왜 kind 인가요?

kubeadm kind
노드 수 1개만 여러 개
버전 선택 불가 가능
만드는 시간 약 1분 약 30초

서버 여러 대에 Pod 가 나뉘는 모습을 보려면 노드가 여러 개여야 합니다.

0-2. kubectl 이 이 클러스터를 보고 있는지 확인

kubectl config current-context

출력: docker-desktop

다른 이름이 나온다면

회사 업무 등으로 다른 클러스터를 쓰던 분은 kubectl 이 그 클러스터를 보고 있을 수 있습니다. 실습 클러스터로 바꿉니다.

kubectl config use-context docker-desktop

실습이 끝나면 원래 쓰던 컨텍스트로 되돌리세요(kubectl config get-contexts 로 목록 확인).

kubectl version

출력 예시:

Client Version: v1.36.1
Kustomize Version: v5.7.1
Server Version: v1.36.1
version difference between client (1.34) and server (1.36) exceeds the supported minor version skew 경고가 나온다면

예전에 따로 설치한 오래된 kubectl 이 먼저 실행되고 있는 것입니다(실제로 겪음).

  • 확인: macOS which -a kubectl / Windows Get-Command kubectl -All
  • Docker Desktop 의 kubectl 위치: macOS /usr/local/bin/kubectl, Windows %LOCALAPPDATA%\Programs\DockerDesktop\resources\bin\kubectl.exe (또는 C:\Program Files\Docker\Docker\resources\bin\kubectl.exe)
  • 오래된 것을 지우거나 PATH 순서를 바꾸세요. 잘 모르겠으면 문의해 주세요.

실습 1. 클러스터 둘러보기

1-1. 노드 목록

kubectl get nodes

출력 예시 (노드 3개):

NAME                    STATUS   ROLES           AGE   VERSION
desktop-control-plane   Ready    control-plane   78s   v1.36.1
desktop-worker          Ready    <none>          67s   v1.36.1
desktop-worker2         Ready    <none>          67s   v1.36.1
노드 역할
desktop-control-plane Control Plane (관리 본부: apiserver, etcd, scheduler, controller-manager)
desktop-worker, desktop-worker2 Worker Node (방명록 같은 앱 Pod 가 실행되는 곳)

자세히 봅니다.

kubectl get nodes -o wide

출력 예시: 가로로 길어서 오른쪽으로 스크롤해서 보세요.

NAME                    STATUS   ROLES           AGE   VERSION   INTERNAL-IP   EXTERNAL-IP   OS-IMAGE                       KERNEL-VERSION                             CONTAINER-RUNTIME
desktop-control-plane   Ready    control-plane   79s   v1.36.1   172.23.0.3    <none>        Debian GNU/Linux 13 (trixie)   6.6.87.2-microsoft-standard-WSL2 (amd64)   containerd://2.3.1
desktop-worker          Ready    <none>          68s   v1.36.1   172.23.0.2    <none>        Debian GNU/Linux 13 (trixie)   6.6.87.2-microsoft-standard-WSL2 (amd64)   containerd://2.3.1
desktop-worker2         Ready    <none>          68s   v1.36.1   172.23.0.4    <none>        Debian GNU/Linux 13 (trixie)   6.6.87.2-microsoft-standard-WSL2 (amd64)   containerd://2.3.1
눈여겨볼 것

  • OS-IMAGE: 노드 안의 OS 입니다. 노트북이 macOS / Windows 여도 노드는 리눅스입니다(1주차의 리눅스 VM 안에서 돌기 때문).
  • CONTAINER-RUNTIME: containerd 입니다. 1주차에 본 그 containerd 입니다.

1-2. 노드의 정체: 컨테이너

kind 방식에서는 노드 하나하나가 컨테이너입니다. Docker Desktop 대시보드 Kubernetes 화면에서 노드 목록을 보거나, 설정의 Show system containers (advanced) 를 켜면 docker ps 에도 노드 컨테이너가 보입니다.

"서버 3대" 처럼 보이지만 실제로는 노트북 안의 컨테이너 3개입니다. 원리를 배우기에는 충분하고, 실제 서버 클러스터와 명령은 똑같습니다.

1-3. 관리 본부의 구성 요소들

kubectl get pods -n kube-system

출력 예시:

NAME                                            READY   STATUS    RESTARTS   AGE
coredns-589f44dc88-jv6r9                        1/1     Running   0          69s
coredns-589f44dc88-pxbhk                        1/1     Running   0          69s
etcd-desktop-control-plane                      1/1     Running   0          78s
kindnet-kg5rv                                   1/1     Running   0          68s
kindnet-kk4jr                                   1/1     Running   0          70s
kindnet-n7d4w                                   1/1     Running   0          68s
kube-apiserver-desktop-control-plane            1/1     Running   0          76s
kube-controller-manager-desktop-control-plane   1/1     Running   0          76s
kube-proxy-gpv8r                                1/1     Running   0          68s
kube-proxy-hdbpr                                1/1     Running   0          70s
kube-proxy-jvtsc                                1/1     Running   0          68s
kube-scheduler-desktop-control-plane            1/1     Running   0          78s
강의 노트의 그림이 실제로 떠 있습니다

이름에 들어간 것 강의 노트의 구성 요소
kube-apiserver-... 창구 (apiserver)
etcd-... 장부 (etcd)
kube-scheduler-... 배차 (scheduler)
kube-controller-manager-... 감독 (controller-manager)
kube-proxy-... 교통 정리 (노드마다 1개씩)
coredns-... 클러스터 안의 DNS (8주차 Service 이름 찾기)
kindnet-... Pod 끼리 통신하게 해 주는 네트워크 플러그인(CNI)

Kubernetes 의 구성 요소 자체도 Pod 로 돌고 있습니다.

1-4. Namespace 목록

kubectl get namespaces

출력 예시:

NAME                 STATUS   AGE
default              Active   5m
kube-node-lease      Active   5m
kube-public          Active   5m
kube-system          Active   5m
local-path-storage   Active   5m

local-path-storage 는 9주차에 쓸 저장소(볼륨) 자동 생성기가 있는 곳입니다.


실습 2. 첫 Pod (명령형)

docker run 처럼 명령 한 줄로 Pod 를 만들어 봅니다.

kubectl run study-nginx --image=nginx:1.30-alpine
kubectl get pods

출력 예시: 처음에는 ContainerCreating, 몇 초 뒤 Running 이 됩니다.

NAME          READY   STATUS    RESTARTS   AGE
study-nginx   1/1     Running   0          7s

상태가 바뀌는 것을 계속 보려면 kubectl get pods -w (Ctrl + C 로 빠져나옴)

어느 노드에 배치됐는지 봅니다.

kubectl get pods -o wide

출력 예시:

NAME          READY   STATUS    RESTARTS   AGE   IP           NODE             NOMINATED NODE   READINESS GATES
study-nginx   1/1     Running   0          8s    10.244.2.4   desktop-worker   <none>           <none>

scheduler 가 Worker Node 중 하나를 골라 배치했습니다. 사람마다 다른 노드가 나올 수 있습니다.

2-1. 무슨 일이 있었는지: describe 의 Events

kubectl describe pod study-nginx

출력 예시 (맨 아래 Events 부분):

Events:
  Type    Reason     Age   From               Message
  ----    ------     ----  ----               -------
  Normal  Scheduled  8s    default-scheduler  Successfully assigned default/study-nginx to desktop-worker
  Normal  Pulled     8s    kubelet            spec.containers{study-nginx}: Container image "nginx:1.30-alpine" already present on machine and can be accessed by the pod
  Normal  Created    8s    kubelet            spec.containers{study-nginx}: Container created
  Normal  Started    8s    kubelet            spec.containers{study-nginx}: Container started
Events 는 강의 노트 3-3 의 흐름 그대로입니다

Scheduled(scheduler 가 노드 배정) → Pulling / Pulled(kubelet 이 이미지 받음) → Created / Started(containerd 가 컨테이너 실행)

2-2. 로그와 삭제

kubectl logs study-nginx
kubectl delete pod study-nginx

실습 3. 방명록 Pod (YAML, 선언형)

3-1. 작업 폴더와 YAML 파일

macOS:

mkdir -p ~/docker-study/k8s
cd ~/docker-study/k8s

Windows (PowerShell):

New-Item -ItemType Directory -Force "$HOME\docker-study\k8s"
cd "$HOME\docker-study\k8s"

VS Code 로 k8s 폴더를 열고 pod.yaml 을 만듭니다. 내아이디 를 본인 Docker Hub 아이디로 바꾸세요.

apiVersion: v1
kind: Pod
metadata:
  name: guestbook
  labels:
    app: guestbook
spec:
  containers:
    - name: web
      image: 내아이디/guestbook:v1
      ports:
        - containerPort: 8000

3-2. 적용

kubectl apply -f pod.yaml
kubectl get pods -o wide --show-labels

출력 예시:

NAME        READY   STATUS    RESTARTS   AGE   IP           NODE             NOMINATED NODE   READINESS GATES   LABELS
guestbook   1/1     Running   0          8s    10.244.2.5   desktop-worker   <none>           <none>            app=guestbook

LABELS 에 app=guestbook 이 보입니다. 7주차부터 이 라벨이 중요해집니다.

3-3. 브라우저로 접속: port-forward

Pod 는 클러스터 안의 IP(10.244.x.x)를 가져서 노트북에서 바로 접속할 수 없습니다. 테스트용으로 노트북 포트를 Pod 에 연결합니다.

kubectl port-forward pod/guestbook 8080:8000

출력 예시: 이 터미널은 연결을 유지하는 동안 그대로 둡니다.

Forwarding from 127.0.0.1:8080 -> 8000
Forwarding from [::1]:8080 -> 8000

브라우저에서 http://localhost:8080 → 방명록 v1 이 보입니다.

HOSTNAME 을 보세요

응답한 서버(HOSTNAME) 가 Docker 때처럼 이상한 ID 가 아니라 guestbook(Pod 이름) 입니다. Kubernetes 는 Pod 이름을 호스트 이름으로 씁니다.

다 봤으면 port-forward 터미널에서 Ctrl + C 로 끊습니다.

실습 중 port-forward 를 켜 둔 채 다른 명령을 치려면 터미널을 하나 더 여세요.

3-4. Pod 안 들여다보기

kubectl exec guestbook -- hostname
kubectl exec guestbook -- env
kubectl logs guestbook

출력 예시 (env 일부):

APP_VERSION=v1
APP_COLOR=royalblue
KUBERNETES_SERVICE_HOST=10.96.0.1
...

3-5. 같은 파일을 다시 apply 하면?

kubectl apply -f pod.yaml

출력: pod/guestbook unchanged

선언형이라서 "이미 원하는 상태" 면 아무것도 하지 않습니다. kubectl run 을 두 번 하면 "이미 있다" 는 에러가 나는 것과 비교해 보세요.


실습 4. Pod 를 지우면?

kubectl delete -f pod.yaml
kubectl get pods

출력:

pod "guestbook" deleted from default namespace
No resources found in default namespace.
아무도 다시 만들어 주지 않습니다

Pod 를 직접 만들면 지워지거나 노드가 죽었을 때 그대로 사라집니다. "항상 N개 유지" 를 책임지는 것은 Deployment 입니다 → 7주차.


실습 5. 고장 난 Pod 진단하기

5-1. 이미지 이름 오타: ImagePullBackOff

일부러 guestbook 을 guestbok 으로 틀리게 씁니다.

kubectl run study-typo --image=내아이디/guestbok:v1

20초쯤 기다린 뒤:

kubectl get pod study-typo

출력 예시:

NAME         READY   STATUS             RESTARTS   AGE
study-typo   0/1     ImagePullBackOff   0          20s

원인을 찾아봅니다.

kubectl describe pod study-typo

출력 예시 (Events 일부):

  Warning  Failed     7s (x2 over 20s)  kubelet  ... Failed to pull image "내아이디/guestbok:v1": failed to pull and unpack image "docker.io/내아이디/guestbok:v1": failed to resolve reference "docker.io/내아이디/guestbok:v1": pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed
  Warning  Failed     7s (x2 over 20s)  kubelet  ... Error: ErrImagePull
  Normal   BackOff    19s               kubelet  ... Back-off pulling image "내아이디/guestbok:v1"
읽는 법

  • repository does not exist → 저장소 이름이 틀렸거나, 비공개 저장소입니다.
  • ErrImagePull (받기 실패) → ImagePullBackOff (잠시 쉬었다가 다시 시도하는 중). 쉬는 시간은 점점 늘어납니다.
  • 이미지 문제는 logs 에는 아무것도 없습니다. 컨테이너가 시작조차 못 했기 때문입니다. describe 의 Events 를 보세요.

kubectl delete pod study-typo

5-2. 앱이 계속 죽음: CrashLoopBackOff

시작하자마자 에러로 끝나는 컨테이너를 만듭니다.

kubectl run study-crash --image=alpine:3.24 -- sh -c "echo 'something wrong'; exit 1"

40초쯤 기다린 뒤:

kubectl get pod study-crash

출력 예시: RESTARTS 가 계속 올라가고, STATUS 가 Error 와 CrashLoopBackOff 를 번갈아 보입니다.

NAME          READY   STATUS             RESTARTS      AGE
study-crash   0/1     CrashLoopBackOff   3 (27s ago)   42s

이번에는 로그에 원인이 있습니다.

kubectl logs study-crash

출력: something wrong

kubectl describe pod study-crash

출력 예시 (일부):

    Last State:     Terminated
      Reason:       Error
      Exit Code:    1
두 고장의 차이

ImagePullBackOff CrashLoopBackOff
무슨 상황? 이미지를 받지 못함 이미지는 받았는데 앱이 실행 후 죽음
어디를 보나? describe 의 Events logs + describe 의 Exit Code
흔한 원인 이름·태그 오타, 비공개 저장소 설정 누락(환경 변수, DB 주소), 코드 에러

--restart 를 주지 않아도 Pod 는 기본으로 계속 재시작을 시도합니다(restartPolicy: Always).

kubectl delete pod study-crash

실습 6. Namespace

kubectl create namespace study
kubectl apply -f pod.yaml -n study
kubectl get pods
kubectl get pods -n study

출력 예시:

No resources found in default namespace.
NAME        READY   STATUS    RESTARTS   AGE
guestbook   1/1     Running   0          7s

-n study 를 안 주면 default 를 봅니다. 그래서 첫 번째 명령에는 아무것도 없습니다.

모든 Namespace 를 한 번에 보려면 -A 를 씁니다.

kubectl get pods -A

Namespace 를 지우면 그 안의 모든 것이 함께 지워집니다.

kubectl delete namespace study
kube-system 은 절대 지우거나 건드리지 마세요

클러스터가 고장 납니다. 망가졌다면 Docker Desktop Kubernetes 설정 → Reset cluster 로 초기화할 수 있습니다.


실습 7. 정리

kubectl get pods -A | grep study

Windows PowerShell 은 kubectl get pods -A | Select-String study

아무것도 안 나오면 끝입니다. 클러스터는 지우지 마세요. 7주차에 계속 씁니다.

노트북이 무거우면

Docker Desktop Kubernetes 화면에서 Stop 으로 클러스터를 잠시 꺼 둘 수 있습니다. 다음 실습 전에 다시 켜면 됩니다.


Docker Hub 에 이미지를 못 올렸다면

Docker Desktop 의 Kubernetes 는 내 노트북에 있는 이미지도 쓸 수 있습니다(실제로 확인함). 4주차 실습 1~4 로 guestbook:v1, guestbook:v2 를 빌드해 두었다면 pod.yaml 의 이미지를 이렇게 바꾸세요.

      image: guestbook:v1

다만 이 방법은 내 노트북에서만 통합니다. 실제 서버 클러스터는 레지스트리(Docker Hub 등)에서 받아야 하므로, 시간이 날 때 4주차 실습 5~6 을 꼭 해 두세요.


자주 나는 문제와 해결

증상 원인 해결
The connection to the server ... was refused / Unable to connect to the server 클러스터가 꺼져 있거나 kubectl 이 다른 클러스터를 봄 Docker Desktop 에서 Kubernetes running 확인, kubectl config use-context docker-desktop
version difference between client ... and server ... exceeds the supported minor version skew 오래된 kubectl 이 먼저 실행됨 실습 0-2 의 경고 상자 참고
클러스터 생성이 오래 걸리거나 실패 메모리 부족 다른 프로그램 종료, 노드 수를 2 또는 1 로 줄여서 다시 생성
ImagePullBackOff 이미지 이름·태그 오타, Docker Hub 에 안 올림, 비공개 저장소 describe Events 확인, Docker Hub 웹에서 이름 확인
CrashLoopBackOff 앱이 시작 후 죽음 kubectl logs 이름 (이전 실행 로그는 --previous)
port-forward 후 bind: address already in use / unable to listen on any of the requested ports 8080 을 다른 것이 사용 중 (5주차 Compose 등) docker compose down 하거나 8081:8000 처럼 다른 포트 사용
Error from server (AlreadyExists) 같은 이름이 이미 있음 (kubectl run 두 번 등) kubectl delete pod 이름 후 다시
YAML apply 시 error converting YAML to JSON 들여쓰기·탭 문제 5주차 YAML 주의사항 참고

오늘 쓴 명령어 정리

명령어 하는 일
kubectl config current-context / use-context 이름 지금 보는 클러스터 확인 / 바꾸기
kubectl version 클라이언트·서버 버전
kubectl get nodes [-o wide] 노드 목록
kubectl get pods [-o wide] [--show-labels] [-n 이름 / -A] [-w] Pod 목록
kubectl run 이름 --image=이미지 [-- 명령] Pod 하나 바로 만들기 (명령형)
kubectl apply -f 파일.yaml [-n 이름] 파일대로 만들기·바꾸기 (선언형)
kubectl describe pod 이름 상세 + Events
kubectl logs 이름 [--previous] 로그
kubectl exec [-it] 이름 -- 명령 Pod 안에서 명령 실행
kubectl port-forward pod/이름 8080:8000 노트북 포트 → Pod 포트 (테스트용)
kubectl delete pod 이름 / delete -f 파일 삭제
kubectl create namespace 이름 / delete namespace 이름 Namespace 만들기 / 지우기
kubectl explain pod.spec.containers YAML 필드 설명

복습 과제

확인 퀴즈

  1. Control Plane 의 구성 요소 4가지와 각각의 역할은?
  2. Worker Node 에서 실제로 컨테이너를 실행하는 구성 요소는? 1주차에 본 것과 어떤 관계인가요?
  3. Pod 를 kubectl delete 로 지우면 다시 생기나요? 왜 그런가요?
  4. ImagePullBackOff 와 CrashLoopBackOff 는 각각 어떤 상황이고, 원인은 어디서 확인하나요?
  5. kubectl apply -f pod.yaml 을 두 번 하면 어떻게 되나요? 이것을 무엇이라고 부르나요?
  6. 방명록 화면의 HOSTNAME 이 Docker 때와 다르게 guestbook 으로 나온 이유는?

도전 과제 (선택)

  1. kubectl run study-gen --image=nginx:1.30-alpine --dry-run=client -o yaml 을 실행해 보세요. Pod 를 만들지 않고 YAML 만 출력합니다. YAML 을 처음부터 쓰기 어려울 때 쓰는 요령입니다.
  2. kubectl get pod guestbook -o yaml 로 실행 중인 Pod 의 전체 YAML 을 보고, 내가 쓰지 않은 status: 부분에서 podIP 와 phase 를 찾아보세요.
  3. Docker Desktop 대시보드의 Kubernetes 화면에서 Namespace 를 바꿔 가며 Pod 목록을 보세요. 터미널로 본 것과 같은 정보가 나옵니다.
다음 주 예고: 7주차 Deployment

오늘 Pod 는 지우면 그대로 사라졌습니다. 다음 주에는 "방명록 Pod 를 항상 3개 유지해" 라고 선언하는 Deployment 를 만들고, Pod 를 지워도 스스로 되살아나는 것, 그리고 v1 → v2 무중단 업데이트와 되돌리기(롤백) 를 해 봅니다.


네비게이션

이전 목록 다음
◀ 6주차 강의 노트 목록으로 7주차 강의 노트 ▶